Agent 上下文工程
前置：写过一个会调工具的 Agent，见过它跑十几轮以上。不需要懂模型内部。
本专题回答：为什么 Agent 跑久了会变笨，以及每一轮该往上下文里放什么、删什么、挪到哪去。
一个跑了四十轮的 Agent，上下文从 3K 涨到 180K。窗口还没满，但它开始重复调已经调过的工具、忘记第五轮定下的约束、对着一份自己十轮前读过的文件再读一遍。
这不是模型退化，是上下文里能用的东西被不能用的东西挤掉了。上下文工程要解决的就是这件事：在每一轮里决定往那个有限的窗口里放什么、不放什么、放在哪个位置。
先约定几个词，本专题全程使用 ：
| 词 | 意思 |
|---|---|
| 上下文工程 | 在推理时策划并维护那组进入模型的 token。区别于提示工程 —— 后者只管怎么把一次指令写好，前者管的是每一轮该带什么进来 |
| 注意力预算 | 一个类比：模型对上下文的有效利用能力是有限的，越长越摊薄。它不是硬上限，而是一条持续下滑的曲线 |
| 上下文腐烂（context rot） | 输入变长导致模型表现变差的现象，即使任务本身没变难。02 篇给实测形态 |
| 压缩（compaction） | 把旧内容总结成一段摘要，替换掉原文。有损，但保留语义 |
| 裁剪（context editing） | 直接删掉特定内容（比如老的工具结果），不做总结。更省，但删掉就是删掉了 |
| 卸载（offload） | 把内容挪到上下文之外（文件、子 Agent、外部存储），需要时再取回一小部分 |
| 前缀缓存 | 模型服务对请求前缀的缓存。前缀有一个字节变化，后面全部要重算 |
| 延迟加载（defer_loading） | 工具定义先不进上下文，等模型搜索到再加载。05 篇的主要手段 |
一、三组问题
二、七篇正文
| # | 标题 | 读完能回答的问题 |
|---|---|---|
| 01 | 窗口里装了什么 | 我这 180K token 到底是被谁吃掉的？哪一块涨得最快？「窗口没满」和「模型还用得动」是不是一回事 |
| 02 | 上下文腐烂 | 同一道题，只是把输入拉长，模型就答错了 —— 这是我的错觉还是真的？18 个模型的实测长什么样 |
| 03 | 压缩与裁剪 | 内容太多了，该总结成摘要还是直接删掉？两者分别会在什么地方悄悄失效、悄悄多花钱 |
| 04 | 卸载到外部 | 能不能把东西挪到窗口外面去，用的时候再取？写文件、开子 Agent、临时检索，这三条路各自把麻烦推给了谁 |
| 05 | 工具与检索结果的占用 | 我还一句话没说，光工具定义就占了两万 token 怎么办？工具超过多少个模型就开始选错 |
| 06 | 前缀缓存与排布 | 为什么我删掉了一些内容，账单反而更贵了？什么改动会让缓存整段作废，怎么验证有没有命中 |
| 07 | 观测与落地 | 上面这些手段该按什么顺序上？该盯哪几个数字才知道有没有起作用 |
只读两篇的话：05 篇（工具与检索结果）和 06 篇（前缀缓存）。前者是省得最多的一处，后者决定你省下来的 token 会不会被缓存失效吃回去。
三、三个需要先知道的前提
3.1 "上下文腐烂"有实测支撑，不是修辞
Chroma 2025 年 7 月的技术报告在 18 个模型（含 GPT-4.1、Claude 4、Gemini 2.5、Qwen3 系列）上做了控制变量实验，结论是模型并不均匀地使用上下文：同一个任务，只把输入拉长，表现就会下降。
更早的《Lost in the Middle》（arXiv 2307.03172）给出了位置维度的版本：相关信息放在开头或结尾时表现最好，放在中间显著变差 —— 即使是专门做长上下文的模型也一样。
细节和三个反直觉结论在 02 篇。
3.2 压缩、裁剪、卸载是三件事，经常被当成一件
| 手段 | 做什么 | 内容还在不在 | API 层的对应物 |
|---|---|---|---|
| 压缩 | 把旧内容总结成一段摘要 | 语义在，原文没了 | compact_20260112，beta compact-2026-01-12 |
| 裁剪 | 直接删掉特定块（老工具结果、思考块） | 不在了 | clear_tool_uses_20250919 / clear_thinking_20251015，beta context-management-2025-06-27 |
| 卸载 | 挪到窗口外，用时再取一小部分 | 完整在外部 | 记忆 工具、子 Agent、你自己的文件系统 |
三者不是替代关系，代价也完全不同 —— 压缩要多花一次模型调用，裁剪不花钱但会破缓存，卸载不花钱但要多花模型轮次。03 篇和 04 篇分别展开。
3.3 每一次上下文改动都是一次缓存事件
这是这一层最容易被忽略、也最直接影响账单的一条。缓存读取的价格约是常规输入的十分之一，缓存写入约是 1.25 倍 —— 把一段本来能命中缓存的前缀改掉，省下的 token 常常不如多付的缓存写入贵。
官方文档在裁剪那一节专门给了一个参数来应对：clear_at_least 指定"至少要清掉这么多 token 才值得执行这次清理"。这个参数的存在本身就说明了问题的量级。06 篇是这条前提的展开。
四、下面这些参数和材料，正文里会反复引用
4.1 三类 API 能力
| 能力 | 标识 | Beta 头 | 关键默认值 |
|---|---|---|---|
| 服务端压缩 | compact_20260112 | compact-2026-01-12 | 触发阈值 150,000 输入 token，最低可设 50,000 |
| 工具结果裁剪 | clear_tool_uses_20250919 | context-management-2025-06-27 | 触发 100,000 输入 token，保留最近 3 次工具调用 |
| 思考块裁剪 | clear_thinking_20251015 | 同上 | 默认行为按模型档次不同，跨档运行时必须显式设 keep |
| 工具搜索（正则） | tool_search_tool_regex_20251119 | 无 | 每次搜索默认返回 5 个工具，最多 10,000 个延迟加载工具 |
| 工具搜索（BM25） | tool_search_tool_bm25_20251119 | 无 | 同上 |
逐条拆在 03 和 05 篇。注意压缩与裁剪是两套独立的 beta，混用一个 beta 头会被拒。
4.2 两份实证材料
| 材料 | 时间 | 在本专题里的角色 |
|---|---|---|
| Chroma《Context Rot》技术报告 | 2025-07 | 02 篇的主要依据。18 个模型、多组控制变量实验 |
| Lost in the Middle（arXiv 2307.03172） | 2023-07（2023-11 修订） | 位置效应的出处，06 篇排布建议的依据之一 |
4.3 一套官方方法论
Anthropic 的《Effective context engineering for AI agents》是这一层目前最完整的官方说法：把上下文当成一份有限的预算来花，长任务靠压缩、结构化笔记、子 Agent 三种手段撑住。
它值得先读一遍，但读完你会发现一件事 —— 它讲的几乎全是「这三招怎么用」，很少讲「这一招什么时候会反过来咬你」。比如压缩要额外付一次模型调用的钱，裁剪不花钱但会把前缀缓存打掉，卸载不花钱但会多绕几轮模型。03 和 04 篇按同样的划分讲，但每一招后面都会把这笔账算出来。
五、与其他专题的关系
- Agent 记忆：记忆负责"跨会话存什么"，本专题负责"这一轮往窗口里放什么"。记忆读回来之后的注入位置与预算分配，是本专题 06 篇的内容
- Agent 编排范式：子 Agent 隔离上下文（04 篇）同时也是一种编排选择，那个专题讲它的调度语义，本篇讲它的上下文账
- Multi-Agent 产品源码分析：那个专题拆的几个产品里，上下文管理策略是最主要的差异点之一
- Agent 可观测性：07 篇要打的那几个点，落在那 个专题定义的 span 属性上
同板块的其他专题：Agent 框架横向对比 | Agent 编排范式 | Multi-Agent 产品源码分析